<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Support for QSettings &mdash; PyQt snapshot-4.9.5-9eb6aac99275 Reference Guide</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '#',
        VERSION:     'snapshot-4.9.5-9eb6aac99275',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/logo_tn.ico"/>
    <link rel="top" title="PyQt snapshot-4.9.5-9eb6aac99275 Reference Guide" href="index.html" />
    <link rel="next" title="Integrating Python and QML" href="qml.html" />
    <link rel="prev" title="Python Objects and QVariant" href="pyqt_qvariant.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="qml.html" title="Integrating Python and QML"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="pyqt_qvariant.html" title="Python Objects and QVariant"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">PyQt snapshot-4.9.5-9eb6aac99275 Reference Guide</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="support-for-qsettings">
<h1>Support for QSettings<a class="headerlink" href="#support-for-qsettings" title="Permalink to this headline">¶</a></h1>
<p>
<span class="versionmodified">New in version v4.8.3.</span></p>
<p>Qt provies the <tt class="docutils literal"><span class="pre">QSettings</span></tt> class as a platform independent API for the
persistent storage and retrieval of application settings.  Settings are
retrieved using the <tt class="docutils literal"><span class="pre">QSettings.value()</span></tt> method which, when using v1 of PyQt&#8217;s
<tt class="docutils literal"><span class="pre">QVariant</span></tt> API returns a <tt class="docutils literal"><span class="pre">QVariant</span></tt> object.  An application will then
typically convert the <tt class="docutils literal"><span class="pre">QVariant</span></tt> to the appropriate fundamental type using
<tt class="docutils literal"><span class="pre">QVariant.toBool()</span></tt>, <tt class="docutils literal"><span class="pre">QVariant.toInt()</span></tt>.</p>
<p>The explicit use of these conversion methods works around a problem with the
way different platforms implement the storage of settings.  Some platforms only
ever store string values which means that the type of the original value is
lost.  Explicitly calling a conversion method provides the missing type
information about the value being retrieved.</p>
<p>A problem then arises when v2 of the <tt class="docutils literal"><span class="pre">QVariant</span></tt> API is used (i.e. the default
for Python v3) because those explicit conversion methods are not available.
Therefore a setting with an integer value of <tt class="docutils literal"><span class="pre">42</span></tt> may be retrieved as a
string value of <tt class="docutils literal"><span class="pre">'42'</span></tt>.  This inconsistency is made worse by being platform
specific.</p>
<p>As a solution to the problem PyQt&#8217;s implementation of <tt class="docutils literal"><span class="pre">QSettings.value()</span></tt>
takes an optional third argument called <tt class="docutils literal"><span class="pre">type</span></tt>.  This is either a Python type
object, e.g. <tt class="docutils literal"><span class="pre">int</span></tt>, or a string that is the name of a C++ type, e.g.
<tt class="docutils literal"><span class="pre">'QStringList'</span></tt>.  The value returned will be an object of the requested type.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="kn">import</span> <span class="n">QSettings</span><span class="p">,</span> <span class="n">QPoint</span>

<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="s">&#39;foo&#39;</span><span class="p">)</span>

<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">&#39;int_value&#39;</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">&#39;point_value&#39;</span><span class="p">,</span> <span class="n">QPoint</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">12</span><span class="p">))</span>

<span class="c"># This will write the setting to the platform specific storage.</span>
<span class="k">del</span> <span class="n">settings</span>

<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="s">&#39;foo&#39;</span><span class="p">)</span>

<span class="n">int_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">&#39;int_value&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">&quot;int_value: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">int_value</span><span class="p">))</span>

<span class="n">point_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">&#39;point_value&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">QPoint</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">&quot;point_value: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">point_value</span><span class="p">))</span>
</pre></div>
</div>
<p>When this is executed then the following will be displayed for all platforms:</p>
<div class="highlight-python"><pre>int_value: 42
point_value: PyQt4.QtCore.QPoint(10, 20)</pre>
</div>
<p>If the value of the setting is a container (corresponding to either
<tt class="docutils literal"><span class="pre">QVariantList</span></tt>, <tt class="docutils literal"><span class="pre">QVariantMap</span></tt> or <tt class="docutils literal"><span class="pre">QVariantHash</span></tt>) then the type is applied
to the contents of the container.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="kn">import</span> <span class="n">QSettings</span>

<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="s">&#39;foo&#39;</span><span class="p">)</span>

<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">&#39;list_value&#39;</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="n">settings</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s">&#39;dict_value&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;one&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">&#39;two&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>

<span class="c"># This will write the setting to the platform specific storage.</span>
<span class="k">del</span> <span class="n">settings</span>

<span class="n">settings</span> <span class="o">=</span> <span class="n">QSettings</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="s">&#39;foo&#39;</span><span class="p">)</span>

<span class="n">list_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">&#39;list_value&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">&quot;list_value: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">list_value</span><span class="p">))</span>

<span class="n">dict_value</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">value</span><span class="p">(</span><span class="s">&#39;dict_value&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">&quot;dict_value: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">dict_value</span><span class="p">))</span>
</pre></div>
</div>
<p>When this is executed then the following will be displayed for all platforms:</p>
<div class="highlight-python"><pre>list_value: [1, 2, 3]
dict_value: {'one': 1, 'two': 2}</pre>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/logo.png" alt="Logo"/>
            </a></p>
            <h4>Previous topic</h4>
            <p class="topless"><a href="pyqt_qvariant.html"
                                  title="previous chapter">Python Objects and QVariant</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="qml.html"
                                  title="next chapter">Integrating Python and QML</a></p>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="qml.html" title="Integrating Python and QML"
             >next</a> |</li>
        <li class="right" >
          <a href="pyqt_qvariant.html" title="Python Objects and QVariant"
             >previous</a> |</li>
        <li><a href="index.html">PyQt snapshot-4.9.5-9eb6aac99275 Reference Guide</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2011 Riverbank Computing Limited.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
    </div>
  </body>
</html>